home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / u_man / cat1 / cvinstr.z / cvinstr
Text File  |  1998-10-30  |  6KB  |  132 lines
  1.  
  2.  
  3.  
  4. CCCCVVVVIIIINNNNSSSSTTTTRRRR((((1111))))                                                          CCCCVVVVIIIINNNNSSSSTTTTRRRR((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      cvinstr - add WorkShop Performance instrumentation code to a program
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ccccvvvviiiinnnnssssttttrrrr [ options ] in_prog_name
  13.  
  14. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  15.      _c_v_i_n_s_t_r is a program which reads an executable program, and writes an
  16.      equivalent program containing additional instrumentation code used for
  17.      performance measurment of the executable.  The additional code either
  18.      maintains an array of counts representing the number of times various
  19.      elements of the program are executed, or the number of statistical
  20.      samples that found the PC at various values, or both.  If the target
  21.      program uses dynamic shared libraries, they are also instrumented.
  22.  
  23.      Normally, _c_v_i_n_s_t_r is invoked during the data collection phase of WorkShop
  24.      Performance tools; it is not intended to be explicitly invoked by a user.
  25.  
  26.      Options are available: (a) to specify that _c_v_i_n_s_t_r count executions of
  27.      each call-site in the program and the first block in each function only;
  28.      (b) to specify execution counts for all basic blocks within the program;
  29.      and/or (c) to instrument to enable statistical PC sampling for the
  30.      program.  Any combination of these options, or none of them may be
  31.      specified.
  32.  
  33.      In the context of _c_v_i_n_s_t_r, a basic block is a region of the program that
  34.      can be entered only at the beginning and exited only at the end; these
  35.      are defined in terms of the instructions in the object program, not in
  36.      terms of basic-blocks defined by the compiler in terms of the source
  37.      code.  If basic block counting is specified, enough information is
  38.      provided to compute exact instruction counts for the program and each of
  39.      its functions, as well as to compute execution counts for each source
  40.      line in the program.  If only function/call-site counts are taken, these
  41.      computations cannot be performed.
  42.  
  43.      A program instrumented for full basic block counting will run
  44.      approximately 2-3 times slower than the original; a program instrumented
  45.      for function/call-site counting will run about 50-100% slower.  Actual
  46.      slowdowns will vary with the nature of the program.
  47.  
  48.      In addition to the instrumented executable and its libraries, _c_v_i_n_s_t_r
  49.      generates a Log file that summarizes various characteristics of the
  50.      program and its shared libraries.  All files are written to a single
  51.      directory, named by the ----DDDD argument to the command.
  52.  
  53.      _c_v_i_n_s_t_r supports the caching of instrumented Dynamic Shared Objects.
  54.      When a DSO is instrumented, it is saved in the directory specified by the
  55.      environment variable CVINSTRLIB.  Experiment directories will contain
  56.      symbolic links to the DSO cache directory.  Caching is enabled by default
  57.      and may be turned off by the -noreuse and -noupdate options.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CCCCVVVVIIIINNNNSSSSTTTTRRRR((((1111))))                                                          CCCCVVVVIIIINNNNSSSSTTTTRRRR((((1111))))
  71.  
  72.  
  73.  
  74. CCCCVVVVIIIINNNNSSSSTTTTRRRR OOOOPPPPTTTTIIIIOOOONNNNSSSS
  75.      ----[[[[nnnnoooo]]]]vvvveeeerrrrbbbboooosssseeee
  76.           Set verbose mode; _c_v_i_n_s_t_r will print out detailed information to the
  77.           .Log file. Default:  ----vvvveeeerrrrbbbboooosssseeee
  78.  
  79.      ----[[[[nnnnoooo]]]]ppppccccssssaaaammmmpppplllleeee
  80.           Instrument the program to invoke PC sampling at start-up time.
  81.           Default:  ----nnnnooooppppccccssssaaaammmmpppplllleeee
  82.  
  83.      ----[[[[nnnnoooo]]]]ffffccccnnnnccccoooouuuunnnnttttssss
  84.           Generate counts for all call-sites and the first basic block of each
  85.           function only.  Default:  ----nnnnooooffffccccnnnnccccoooouuuunnnnttttssss
  86.  
  87.      ----[[[[nnnnoooo]]]]bbbbbbbbccccoooouuuunnnnttttssss
  88.           Generate function and basic-block counts.  Default:  ----bbbbbbbbccccoooouuuunnnnttttssss
  89.  
  90.      ----DDDD _o_u_t_p_u_t__d_i_r_e_c_t_o_r_y
  91.           Specify a directory for writing the output file.  Default is current
  92.           directory, "./".
  93.  
  94.      ----oooo _o_u_t__p_r_o_g__n_a_m_e
  95.           Specify a name for the translation.  Default is to remove any
  96.           leading directory names from the in_prog_name and append "_Instr" to
  97.           the name.
  98.  
  99.      The following options are provided for use by WorkShop/Tester.
  100.  
  101.      ----ccccoooovvvveeeerrrraaaaggggeeee _n_a_m_e
  102.           Name of the coverage file.  This is a command file where complex
  103.           selection critera can be specified.  The ability to trace function
  104.           arguments and function return values is also provided.
  105.  
  106.      ----[[[[nnnnoooo]]]]bbbbrrrraaaannnncccchhhhccccoooouuuunnnnttttssss
  107.           Generate a count bin for each taken branch in the program.  Default:
  108.           ----bbbbrrrraaaannnncccchhhhccccoooouuuunnnnttttssss
  109.  
  110. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  111.      cvperf(1)
  112.  
  113. BBBBUUUUGGGGSSSS
  114.      _c_v_i_n_s_t_r cannot handle stripped programs; it will give a message warning
  115.      the user if it is invoked on a stripped executable.
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  126.  
  127.  
  128.                                                                         PPPPaaaaggggeeee 2222
  129.  
  130.  
  131.  
  132.